lab components / Forms and input

Checkbox

Checkboxes allow users to select one or more items from a list.

Examples Properties Guidelines Notable changes

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { Checkbox } from "@siteimprove/fancylab";

#Examples

#Base checkbox

This interactive input control indicates the current state. By default, it is unchecked.

CodeHTML output

const [checked, setChecked] = useState(false);
return <BaseCheckbox checked={checked} onChange={(e) => setChecked(e.target.checked)} />;

#Checkbox

Provide a label indicating to users what can be selected or deselected.

Label

CodeHTML output

const [checked, setChecked] = useState(false);
return (
	<Checkbox value="value" checked={checked} onChange={(e) => setChecked(e.target.checked)}>
		Label
	</Checkbox>
);

#Checkbox group

When using CheckboxGroup, provide a group label to indicate the category of the options and explain what can be selected.

Default state:
by default, checkboxes are unchecked, meaning no options have been selected. Use checked state when the item is selected.
Indeterminate state:
use the indeterminate state when you have a list of selections, where some items are are selected, and some are unselected.
Disabled state:
when the user expects a predefined set of options, a disabled option is useful to indicate that normally that option would be available, but now it is not available due to a specific condition. If possible, provide hint text or a visual cue to checkbox is disabled to avoid confusion for the user.
Label with dynamic text:
be aware of how the labels will resize and how any visuals surrounding them will be affected.
Label with icon or tooltip:
help the user understand the context of the checkbox.

CodeHTML output

const [selected, setSelected] = useState<string[]>([]);
return (
	<CheckboxGroup onChange={setSelected} value={selected}>
		<CheckboxGroup.Checkbox value="option-1">Regular option</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-2" indeterminate>
			Indeterminate option
		</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-3" disabled>
			Disabled option
		</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-4">
			<Icon>
				<IconApprove />
			</Icon>
			<InlineText>Option with left icon</InlineText>
		</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-5">
			{(props: { checked: boolean; disabled: boolean }) => (
				<>
					<InlineText
						emphasis={props.checked ? "medium" : "normal"}
						lineHeight="multi-line"
						tone={props.disabled ? "subtle" : undefined}
					>
						Option with right icon and dynamic text style
					</InlineText>
					<Icon>
						<IconApprove />
					</Icon>
				</>
			)}
		</CheckboxGroup.Checkbox>
		<Tooltip variant={{ type: "interactive" }} content="Extra info on the option 5">
			<CheckboxGroup.Checkbox value="option-6">Option with tooltip</CheckboxGroup.Checkbox>
		</Tooltip>
	</CheckboxGroup>
);

#Horizontal checkbox group

Make a horizontal group by using the direction prop on the CheckboxGroup component.

CodeHTML output

const [selected, setSelected] = useState<string[]>([]);
return (
	<CheckboxGroup onChange={setSelected} value={selected} direction="horizontal">
		<CheckboxGroup.Checkbox value="option-1">Regular option</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-2" indeterminate>
			Indeterminate option
		</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-3" disabled>
			Disabled option
		</CheckboxGroup.Checkbox>
		<CheckboxGroup.Checkbox value="option-4">
			<Icon>
				<IconApprove />
			</Icon>
			<InlineText>Option with left icon</InlineText>
		</CheckboxGroup.Checkbox>
		<Tooltip variant={{ type: "interactive" }} content="Extra info on the option 5">
			<CheckboxGroup.Checkbox value="option-6">Option with tooltip</CheckboxGroup.Checkbox>
		</Tooltip>
	</CheckboxGroup>
);

#Properties

#Base checkbox

CodePropsHTML output

Property	Description	Defined	Value
checkedRequired	`boolean`Determines if the checkbox appears checked or not	YesNo	truefalse
onChangeRequired	`function`Event for when the state of the checkbox changes	YesNo
idOptional	`string`Id applied to the form control	YesNo
onBlurOptional	`function`Callback for onBlur event	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelOptional	`string`Label of the form control	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
valueOptional	`string`Value of the form control	YesNo
nameOptional	`string`Name applied to the form control	YesNo
invalidOptional	`boolean`Is the form control invalid	YesNo	truefalse
disabledOptional	`boolean`Disables the checkbox, prevent it from changing state	YesNo	truefalse
indeterminateOptional	`boolean`Shows the checkbox as neither checked nor unchecked	YesNo	truefalse
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo

#Checkbox

Label

CodePropsHTML output

Property	Description	Defined	Value
onChangeRequired	`function`Event for when the state of the checkbox changes	YesNo
checkedRequired	`boolean`Determines if the checkbox appears checked or not	YesNo	truefalse
valueRequired	`string`Value of the form control	YesNo
idOptional	`string`Id applied to the form control	YesNo
disabledOptional	`boolean`Disables the checkbox, prevent it from changing state	YesNo	truefalse
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onBlurOptional	`function`Callback for onBlur event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelOptional	`string`Label of the form control	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo
nameOptional	`string`Name applied to the form control	YesNo
invalidOptional	`boolean`Is the form control invalid	YesNo	truefalse
indeterminateOptional	`boolean`Shows the checkbox as neither checked nor unchecked	YesNo	truefalse
childrenOptional	`element`	YesNo

#Checkbox group

Property	Description	Defined	Value
valueRequired	`string[]`Value of the form control	YesNo
onChangeRequired	`function`Callback for onChange event	YesNo
nameOptional	`string`Name applied to the form control	YesNo
idOptional	`string`Id applied to the form control	YesNo
invalidOptional	`boolean`Is the form control invalid	YesNo	truefalse
onBlurOptional	`function`Callback for onBlur event	YesNo
aria-labelOptional	`string`Label of the form control	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
childrenOptional	`element`	YesNo
directionOptional	`"horizontal" \| "vertical"`	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo

#Guidelines

#Best practices

#General

Use Checkbox or CheckboxGroup when

multiple choices are available, and users can choose zero, one, or multiple items from a list.
seven or fewer related items can be selected from a list.
the user needs to confirm, save changes, or take explicit action.
the user can enable or disable a single feature.

#Placement

Checkboxes are typically used in the following places:

Forms
Checkboxes can be used in forms on a full page, in modals, or in side panels. To group multiple options, checkboxes can be placed in the Form element wrapper component or by using the Select component in the multi-select mode. An example of a checkbox in forms can be found in Keyword Monitoring.
Filtering and bulk action
Checkboxes can be used to filter information on a page, in modals, in forms, or within components. Checkboxes can be used in the Select component when using custom option elements. An example of filtering can be found in Activity Plan Overview.
Terms and conditions
Users can indicate whether they agree or disagree with the terms by ticking or unticking a standalone checkbox. Ticked or unticked a checkbox also indicates that an option is enabled or disabled (e.g. "Remember me on this computer"). Examples of terms and conditions can be found on the page of CMS Plugin Setup.
Line Chart
Checkboxes can be used to toggle the visibility of lines on a chart. Examples of a chart can be found on the page of QA overview.

#Style

Checkbox labels are recommended to align to the right of their corresponding base checkboxes. (Cohesive)
Checkbox groups can be positioned vertically or horizontally depending on the use case and the UI structure. Whenever possible, arrange the checkboxes vertically to make it easier for the user to scan and compare the options, especially in a form. (Intuitive)
Checkbox labels can be wrapped into two lines if they are long and viewed on a mobile screen size. A checkbox label should never be truncated, omitted, or replaced with “…”. (Accessible)
Checkbox groups should not be nested. Ensure that all options are on the same level to prevent confusion. (Intuitive)

#Do not use when

The user can only choose one item from a list. In this case, use radios instead.
Each of the items represents an independent feature or behaviour and is not related to each other.
The user does not need to confirm, save, or take explicit action.
The user requires an immediate response or change in the settings. In this case, use the Toggle Switch component instead.

#Accessibility

For designers

A checkbox should have a label.
A checkbox group must have a meaningful name as an aria-label, which helps the screen reader properly announce the group of checkboxes to make it clear that they belong together. To understand what is aria-label, please visit this link.
If possible, add a hint text under the checkbox label to improve the clarity of the action and add further context to the label.
For BaseCheckbox within the form, containing 10, or more options, add buttons for selecting and deselecting all options. For example: “Select 25 links on this page”, or “Select all 35 links”.

For developers

A checkbox must have a visible label. For example: <Checkbox value="Apple">Apple</Checkbox>
A group of checkboxes must be contained in a CheckboxGroup component.
To allow the screen reader to announce a CheckboxGroup meaningfully, the text of the aria-label must be provided by a designer.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

It is recommended that the checkbox label contains three words or less.
Use clear and concise checkbox labels and group labels.
Use sentence case for a group label.
Do not include punctuation after a checkbox label.
Use positive and affirmative labels. For example: “Remember password” instead of “Forget password”.
Whenever possible, provide a hint text indicating how many items users should select from a list of checkboxes. For example: “Select all that apply”, or “Select at least one item”.

The CheckboxGroup component on FancyLab 16.x or prior takes an array of control objects as input/property, which is terse and works well with typechecking, but it plays poorly with composition. As an example, adding a tooltip to a checkbox label is not possible using this structure as well as changing the icon position to after or before the label.

So, in FancyLab 17.x, the CheckboxGroup component was refactored to allow composing other components with them. Now, instead of having a controls object, subcomponents are used to create the controls.

Please find below an example that illustrates the usage before and after these changes. Note that the controls property has been replaced by children of type CheckboxGroup.Checkbox.

#Before

<CheckboxGroup
	onChange={setSelected}
	value={selected}
	controls={[
		{ label: "White Wine", value: "white-wine" },
		{ label: "Red Wine", value: "red-wine" },
	]}
/>

#After

<CheckboxGroup onChange={setSelected} value={selected}>
	<CheckboxGroup.Checkbox value="white-wine">White Wine</CheckboxGroup.Checkbox>
	<CheckboxGroup.Checkbox value="red-wine">Red Wine</CheckboxGroup.Checkbox>
</CheckboxGroup>

Checkbox

This is a Lab component!

#Examples

#Base checkbox

#Checkbox

#Checkbox group

Default state:

Indeterminate state:

Disabled state:

Label with dynamic text:

Label with icon or tooltip:

#Horizontal checkbox group

#Properties

#Base checkbox

#Checkbox

#Checkbox group

#Guidelines

#Best practices

#General

#Placement

Forms

Filtering and bulk action

Terms and conditions

Line Chart

#Style

#Do not use when

#Accessibility

For designers

For developers

#Writing

#Notable changes

#Migrating from FancyLab 16.x to FancyLab 17.x

#Before

#After